feat(connections): connect through a SOCKS5 proxy - #1899
Merged
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #1882
What
Adds a per-connection SOCKS5 proxy as a fourth connection method alongside SSH Tunnel, Cloudflare Tunnel, and Cloud SQL Auth Proxy. The connection form gets a SOCKS Proxy pane with Host, Port (default 1080), and an optional Username and Password (Keychain).
How it works
SOCKSProxyManageractor (Core/SOCKS/) built on Network.framework'sProxyConfiguration(socksv5Proxy:)(macOS 14+). AnNWListeneron a kernel-assigned loopback port relays each driver connection through the proxy; Network.framework performs the SOCKSv5 handshake, including RFC 1929 username/password auth. In-process, no external binary.ATYP=DOMAIN), so names that only resolve behind the proxy work and no DNS query for the DB host leaves the machine. SOCKS5 only; Network.framework has no SOCKS4.NWConnectionin.waitingforever, so tunnel creation probes the path against an app-owned 15s deadline withwithTaskCancellationHandler, keeping the connect cancellable per the CLAUDE.md invariant. Errors name the proxy endpoint.NWParameters.PrivacyContextper tunnel, never the process default, so app traffic (Sparkle, AI providers, plugin registry) is never proxied.allowFailoverstays false so a broken proxy can never silently fall back to a direct connection.ConnectionTunnelKindthrough the existingTunnelManaging/activeTunnelKind/tunneledConnectionmachinery. Tunnel death means the listener failing; individual relay closes are normal query churn and never trigger reconnect.supportsSOCKSProxyis computed fromsupportsSSHinPluginMetadataRegistry(both mean "the driver dials a raw TCP host:port"), so HTTP-API drivers are excluded and no plugin changes or ABI bump are needed.StoredConnectiononly when enabled, is excluded from iCloud sync like the other tunnel modes, and the password lives in the Keychain with delete-on-disable, delete, and duplicate handling.Adjacent fixes (in touched code, separate CHANGELOG entries)
TunnelExclusivityBannerandotherEnabledTunnels(excluding:), listing every conflicting method with a disable button.Tests
FakeSOCKS5Server: an in-process RFC 1928/1929 server on a real loopback listener (same trick asFakeCloudflaredRunner).SOCKSProxyManagerTests: byte round-trip through the proxy, credential negotiation, auth reject, unreachable and silent proxy timeouts, cancel-during-connect returns promptly, remote DNS (capturedATYP=DOMAINbytes), two concurrent relays through one tunnel, close frees the port, recreate replaces the old tunnel.StoredConnectionround-trip, form state round-trip.ConnectionTunnelKindTestsextended to the full 2^4 combination matrix.ConnectionFormTunnelExclusivityTests: pairwise and all-enabled conflict matrix plus the disable action.ConnectionStoragePersistenceTests: duplicate carries all three tunnel modes and secrets; delete removes the SOCKS password.No UI automation: the connect flow needs a reachable SOCKS proxy and database, which is not deterministic in CI. Pane behavior is covered by the view model and coordinator tests above.
Docs
New
docs/databases/socks-proxy.mdx(covers thessh -Duse case and the macOS 15 Local Network prompt), overview matrix and pane table updated, page registered indocs.json.